readme: improved front matter, part 2 #2463
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
6c63ed7 to
f79816b
Compare
martinvonz
reviewed
Oct 29, 2023
joyously
reviewed
Oct 29, 2023
ilyagr
reviewed
Oct 29, 2023
|
I haven't read this super-carefully, but overall it looks really nice. Thank you! |
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
7 times, most recently
from
4a90845 to
b18364d
Compare
ilyagr
reviewed
Oct 30, 2023
ilyagr
reviewed
Oct 30, 2023
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
b18364d to
6fc5256
Compare
ilyagr
changed the title
|
FYI, I renamed the PR (inserted a space) because I kept misreading "frontmatter" as "formatter". A quick Google search seems to suggest that:
|
ilyagr
approved these changes
Oct 31, 2023
There was a problem hiding this comment.
Looks good, thank you!
I'm not sure whether @martinvonz wants to separately approve, but unless I missed something, most/all of the discussions seem resolved.
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
6fc5256 to
d170df2
Compare
|
I went ahead and gave it one more look over and fixed some typos and whatnot; let me know what you think. |
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
d170df2 to
4d386f2
Compare
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
4d386f2 to
b0ad75d
Compare
martinvonz
reviewed
Oct 31, 2023
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
b0ad75d to
3a2cd3e
Compare
martinvonz
reviewed
Nov 1, 2023
martinvonz
reviewed
Nov 1, 2023
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
3a2cd3e to
1cc609f
Compare
ilyagr
reviewed
Nov 1, 2023
das-g
reviewed
Nov 1, 2023
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
1cc609f to
d905820
Compare
Summary: What was going to just be some minor touch-ups to the existing content ended in another rework of the frontmatter, this time primarily the sales pitch and basic feature explanation. The motivation here is simple: you should not just encounter a three-word noun that is a hyperlink to pages with 1,000 words actually explaining the three-word noun itself is. It's jarring! Instead, the frontmatter is longer, expanding on each major selling point and similarity to other tools. It actually *describes* the important, distinct design decisions that tell you what the tool is and does, rather than just link you around a bunch. For example, one immediate thing is that calling jj a "DVCS" is actually kind of odd when it later becomes apparent that you can have multiple data model and commit backends; Google for example uses it in a more centralized manner than others would via Piper/CitC. Calling it a "DVCS" is a bit strange in this sense when *really* what we mean is that the Git data model allows independent copies of the repo. Overall I think this is *much* better for people who are just going to see the README and may or may not bounce off immediately. Signed-off-by: Austin Seipp <[email protected]> Change-Id: I9f0f78e56157ef434ec239710e00f3bd
thoughtpolice
force-pushed
the
aseipp/push-ttqlxuxkwvqw
branch
from
d905820 to
52e361c
Compare
martinvonz
approved these changes
Nov 5, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary: What was going to just be some minor touch-ups to the existing content ended in another rework of the frontmatter, this time primarily the sales pitch and basic feature explanation.
The motivation here is simple: you should not just encounter a three-word noun that is a hyperlink to pages with 1,000 words actually explaining the three-word noun itself is. It's jarring!
Instead, the frontmatter is longer, expanding on each major selling point and similarity to other tools. It actually describes the important, distinct design decisions that tell you what the tool is and does, rather than just link you around a bunch.
For example, one immediate thing is that calling jj a "DVCS" is actually kind of odd when it later becomes apparent that you can have multiple data model and commit backends; Google for example uses it in a more centralized manner than others would via Piper/CitC. Calling it a "DVCS" is a bit strange in this sense when really what we mean is that the Git data model allows independent copies of the repo.
Overall I think this is much better for people who are just going to see the README and may or may not bounce off immediately.
Change-Id: I9f0f78e56157ef434ec239710e00f3bd
Checklist
If applicable:
CHANGELOG.md